home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 011-020 / amok16 / proginfoids < prev    next >
Text File  |  1993-11-04  |  11KB  |  318 lines
  1. ======================================================================
  2.                 AMOK - Amiga Modula Klub Stuttgart
  3.  
  4.                  Standard Identifier für ProgInfo
  5.            (Dokumentationsextraktion aus dem Quelltext)
  6. ======================================================================
  7.  
  8.  
  9.  
  10. Programmkopf
  11. ­­­­­­­­­­­­
  12. Für alle AmokProgramme ist ein Programmkopf vorgeschrieben, der die
  13. wichtigsten Informationen zu diesem enthält.
  14. Bei Modula-2-Programmen muß er vor dem Schlüsselwort MODULE in einem
  15. Kommentar stehen. Er sollte durch "***"- oder "---"-Zeilen hervorgehoben
  16. sein, ein Einrahmen ist jedoch nicht zweckmäßig (da die letzten "*"s in
  17. der Zeile stören).
  18. Der Programmkopf enthält mehrere Einträge, die jeweils mit
  19. ":"Schlüsselwort"." beginnen. Reicht eine Zeile für einen Eintrag nicht
  20. aus, wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und
  21. der Eintrag danach fortgesetzt. Doppelpunkt, Punkt und Schreibweise
  22. sind wichtig, da sonst die Einträge von Doku-Extraktionsprogrammen nicht
  23. gefunden werden.
  24.  
  25. Der Programmkopf muß (!) mindestens folgende Einträge enthalten:
  26.  
  27. :Program.       <Programmname>
  28. :Contents.      <Kurzbeschreibung von Inhalt/Verwendungszweck>
  29. :Author.        <voller Autorenname, kein Pseudonym (!)>
  30. :Copyright.     <Bemerkung über Copyright oder Public Domain>
  31. :Language.      <Sprache, eventuell Bemerkung über Besonderheiten>
  32. :Translator.    <Name des Compilers/Assemblers mit Versionsangabe>
  33. :History.       <Version, Datum, Autor, Bemerkung>
  34.  
  35. Falls notwendig müssen auch folgende Angaben gemacht werden:
  36.  
  37. :Support.       <Hinweis auf von anderen übernomene Programmteile/Ideen>
  38. :Imports.       <Importierte Module außer dem Standardumfang des Compilers>
  39. :Bugs.          <bekannte Fehler>
  40.  
  41. Freiwillig sind diese Angaben:
  42.  
  43. :Address.       <Adresse des Autors>
  44. :Phone.         <seine Telephonnummer>
  45. :Update.        <Angaben über Änderungen, die :History. nicht abdeckt>
  46. :Remark.        <beliebiger Kommentar>
  47. :Usage.         <Usage zB. für CLI-Befehl>
  48.  
  49. Andere Einträge Date,Shortcut,Version sind möglichst nicht mehr zu
  50. benutzen. Fehlende Einträge sollten so bald und gut als möglich
  51. nachgetragen oder rekonstruiert werden.
  52.  
  53.  
  54. Empfehlungen
  55. ­­­­­­­­­­­­
  56. Auf eine strikte festlegung des Programmkopftextes wurde verzichtet. Damit
  57. dieser jedoch einigermaßen einheitlich bleibt sollte man die folgenden
  58. Regeln beachten.
  59.  
  60. Leere Einträge
  61. --------------
  62. Außer den zuerst genannten Pflichteinträgen können eventuell auch welche
  63. entfallen. Am besten läßt man dann den gesammten Eintrag sammt Schlüssel-
  64. wort weg. Als leer gelten außerdem Einträge, die nur aus Leerzeichen,
  65. Sternchen "*" oder Strichen "-" bestehen.
  66. Unsinnige Einträge (zB. ":Imports. bis jetzt noch nichts") sind möglichst
  67. zu unterlassen.
  68.  
  69. :Program.
  70. ---------
  71. Hier sollte der Programmname stehen, der mit dem Filenamen (mit Extension,
  72. zB. "Test.def") übereinstimmen sollte. Reicht der Programmname zur
  73. eindeutigen Indentifizierung nicht aus (z.B. geändertes Modul "Strings")
  74. so steht hinter dem Programmnamen ein entsprechender Kommentar.
  75.  
  76. :Contents.
  77. ----------
  78. Kurzbeschreibung von Programminhalt und -funktion. Die Beschreibung
  79. sollte erklärend sein und nicht nur eine längere Version des Programm-
  80. namens sein (zB.  N I C H T :
  81.  :Program.  InOut.def
  82.  :Contents. Definitionsmodul Input/Output
  83. ).
  84.  
  85. :Author.
  86. --------
  87. Bitte den vollen Namen angeben. Pseudonyme sind unzulässig.
  88. Ein Programm kann auch mehere Autoren haben, z.B. wenn ein PC-Programm
  89. auf den Amiga umgesetzt wurde.
  90.  
  91. :Address.
  92. ---------
  93. Freiwillig ist die Angabe der Adresse des Autors. Sie sollte Straße,
  94. Hausnummer, Postleitzahl, Ort und Land enthalten.
  95.  
  96. :Phone.
  97. -------
  98. Telefonnummer des Autors mit Vorwahl. Zusätzliche Bemerkungen, zB. Zeit-
  99. angaben für Erreichbarkeit, sind zulässig. Hat ein Programm mehere Autoren
  100. (s. oben) so steht hier die Telefonnummer des für dieses Programm
  101. zuständigen Autors, d.h. desjenigen, der eventuelle Fragen am besten
  102. beantworten kann.
  103.  
  104. :Copyright.
  105. -----------
  106. Hieraus sollte ersichtlich sein, ob das Programm frei kopiert werden
  107. darf (Public Domain), ob eine (Shareware-)Gebühr verlangt wird oder
  108. ob das Programm gar nicht weitergegeben werden darf.
  109. Kommentare wie zB. "copy it, but leave my name in" oder ähnliches sind
  110. zulässig. Bei längeren "Plädoyers" sollte allerdings auf eine extra
  111. Datei verwiesen werden.
  112.  
  113. :Language.
  114. ----------
  115. Hier steht im Normalfall "Modula-2". Wenn das Programm INLINE-Assembler-
  116. code enthält, sollte dies hier Vermerkt werden. Ebenso sollte verfahren
  117. werden, wenn das Programm dem Modula-Standard nicht entsprechende
  118. Statements enthält. Dazu gehört unter anderem die seit Version 3.2
  119. mögliche Typenkonversion von ADDRESS/BPTR und die Dereferenzierung
  120. von BPTRn (Zugriff auf BcplPtr^.items). Die normale Verwendung des
  121. Typs BPTR als opaker Typ gehört nicht dazu, denn er ist im Standard-
  122. Modula erlaubt.
  123. Der Sinn hiervon ist es, Leute zu warnen, die Programme auf andere
  124. Compiler umsetzen wollen.
  125.  
  126. :Translator.
  127. ------------
  128. Bezeichnet den Compiler (/Assembler/Interpreter) (normal M2Amiga A+L)
  129. und die Versionsnummer (V3.2d oder V3.1d). Dahinter stehen eventuelle
  130. Hinweise auf Compiler-Bugs, die für dieses Programm relevant sind.
  131.  
  132. :History.
  133. ---------
  134. Dies ist einer der wichtigsten Einträge. Er beinhaltet Informationen
  135. über die Versionen des Programms (Opfer), der entsprechenden
  136. Erstellungs- und Änderungsdaten (Tatzeit), den Autor oder für die
  137. Änderung Veratwortlichen (Täter) sowie eine optionale Bemerkung
  138. (Motiv). Beispiel:
  139.  
  140. :History.       V1.1 [bne] 29.Mar.1989 (bug in Init() fixed)
  141.  
  142. Den Versionsnummern wird später noch ein spezielles Kapitel gewidmet.
  143. Zusammengehörige Definitions- und Implementationsmodule tragen immer
  144. mindestens gleiche Versions- und Revisionsnummer (Branchnummer und
  145. Kennbuchstabe dürfen verschieden sein).
  146. Das Datum besteht aus dem ein- oder zweistelligen Tag, dem Monats-
  147. kürzel (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez) aus drei
  148. Buchstaben und der zwei oder vierstelligen Jahreszahl. Für den Autor
  149. steht ein Kürzel oder für "Externies" der Nachname.
  150.  
  151. :Support.
  152. ---------
  153. Der Fairneß halber sollte man hier Angaben über Beiträge anderer
  154. Personen machen, wenn man Schuldgefühle wegen geklauter Ideen oder
  155. Algorithmen hat.
  156.  
  157. :Imports.
  158. ---------
  159. Importiert das Modul außer den Standardmodulen des Compilers noch
  160. weitere, so müssen diese hier eingetragen werden. Wird eine bestimmte
  161. Version benötigt, folgt auf den Namen des importierten Moduls dessen
  162. Versionsnummer. Es dürfen auch Verweise auf Amok-Disks oder den Autor
  163. gemacht wedren. Beispiel:
  164.  
  165. :Imports.       MemSystem1.3 [bne], List [mif] Amok#7
  166.  
  167. :Bugs.
  168. ------
  169. Sind Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das
  170. Modul fehlerhaft ist, wird dies hier vermerkt. Soweit dies möglich
  171. ist, soll der Fehler möglichst eng eingegrenzt werden (z.B Angabe der
  172. Prozedur, in der er auftritt). Ist ein Modul noch nicht vollständig
  173. ausgetestet, sollte man mit ":Bugs. not tested" warnen. ":Bugs. none"
  174. verpflichtet zu mindestens 99,9% Fehlerfreiheit!
  175.  
  176. :Usage.
  177. -------
  178. bezeichnet die Syntax eines CLI-Befehls und dessen Argumente.
  179. Die Usage wird entweder in EBNF oder mit dem vom Dos-Handbuch und
  180. ARP verwendeten Template angegeben.
  181.  
  182.  
  183. Versionsnummern
  184. ---------------
  185. Die Versionsnummer besteht normalerweise aus zwei Stellen
  186. (version,revision), die durch einen Punkt getrennt sind. Die erste
  187. lauffähige Version wird mit 1.0 bezeichnet. Bei jeder Änderung wird
  188. die zweite Stelle (Revision) um eins erhöht, wobei nach 1.9 die 1.10
  189. und dann 1.11 usw. folgt. Bei sehr tiefgreifenden Neuerungen wird die
  190. erste Stelle (Version) erhöht, die zweite (Revision) springt auf 0.
  191. Die Versionsnummer darf NICHT als Dezimalbruch angesehen werden,
  192. der sich jedesmal um 1/10 erhöht. Eine Revision ist KEINE zehntel
  193. Version und eine Version entspricht NICHT 10 Revisions. Version und
  194. Revision werden unabhängig gezählt !!! Versionsnummern wie 1.09 sind
  195. unzulässig und 1.10 (erste Version, zehnte Revision) steht zwischen
  196. 1.10 und 1.12 und ist nicht gleich 1.1 !
  197. "Hundertstel" Versionen gibt es nicht. Wenn es erforderlich wird,
  198. eine Version nachträglich in eine Reihe einzufügen, wird dies
  199. durch eine zweiten Punkt gekennzeichnet.
  200. Beispiel: Es existieren bereits die Versionen 1.0 bis 1.4 , und
  201. jemand ändert nachträglich die Version 1.2  . Diese bekommt
  202. dann die Nummer 1.2.1 (sog. Branch-Version).
  203. Man kann Versionsreihen auch als Baum darstellen:
  204.  
  205.       1.0
  206.  
  207.        |
  208.        V
  209.  
  210.       1.1
  211.  
  212.        |
  213.        V
  214.  
  215.       1.2
  216.  
  217.        |
  218.       / \
  219.      /   \
  220.     V     V
  221.  
  222.    1.3   1.2.1
  223.  
  224.     |      |
  225.     V      V
  226.  
  227.    1.4    1.2.2
  228.  
  229.     |      usw.
  230.  
  231.    ...
  232.  
  233.     |
  234.     V
  235.  
  236.    1.9
  237.  
  238.     |
  239.     V
  240.  
  241.    1.10
  242.  
  243.    usw.
  244.  
  245.  
  246. Die Zählweise entspricht nicht der von Big Blue, verleitet
  247. aber dafür zu weniger Mißverständnissen, weil man nicht rätseln
  248. muß, ob 3.2 jetzt die auf 3.1 oder auf 3.19 folgende Version ist.
  249. Version und Revision können beliebig hoch werden - Beispiel:
  250. die Libraries der alten 1.2 Workbench trugen die Versionsnummer
  251. 33.180 (dreiunddreißigste Version, hundertachzigste Revision).
  252.  
  253. Wer noch eine feiner abgestufte Unterscheidung machen möchte,
  254. kann der Nummer noch einen Kleinbuchstaben anhängen. Dieser ist
  255. optional und muß nichts über die Reihenfolge aussagen (z.B. 3.2d
  256. für die deutsche und 3.2e für die englische Version).
  257.  
  258.  
  259. Source-Code-Format
  260. ------------------
  261. Damit der Sourcecode einigermaßen übersichtlich ist, wird folgende
  262. Formatierung vorgeschlagen:
  263.  
  264. * In jeder Zeile steht nur eine logische Anweisungseinheit.
  265.  
  266. * Globale Prozeduren, Variablen und Konstanten stehen ganz am Anfang
  267.   der Zeile.
  268.  
  269. * Deklarationen und Prozedurkörper sind gegenüber ihrem CONST, VAR,
  270.   TYPE und PROCEDURE eingerückt.
  271.  
  272. * Programmteile, die lokal zu anderen definiert werden, oder von
  273.   bestimmten Konstrukten eingeschlossen werden, werden jeweils
  274.   relativ zu diesen um ZWEI Zeichen eingerückt.
  275.  
  276. * Zugehörige BEGIN und END, IF, ELSE und END usw. stehen jeweils
  277.   untereinander. Ist ein END mehr als eine Bildschirmseite (25 Zeilen)
  278.   von seinem BEGIN etc. entfernt, steht hinter dem END in Kommentar,
  279.   was dort beendet wurde.
  280.  
  281. * Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT
  282.   steht hinter jeder Zeile ein Semikolon.
  283.  
  284. * Elemente von Mengen, Aufzählungstypen und RECORDs fangen klein an,
  285.   Konstanten fangen klein oder groß an, alles andere immer groß.
  286.   Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben".
  287.  
  288. * Paßt die Parameterliste einer Prozedur nicht in eine Zeile
  289.   (75 Zeichen), werden die Parameter untereinander angeordnet.
  290.  
  291. * Importe werden alphabetisch nach den Namen der Module geordnet.
  292.   Sind Importlisten länger als zwei Zeilen werden auch die importierten
  293.   Objekte alphabetisch sortiert.
  294.  
  295. Beispiel:
  296.  
  297. CONST
  298.   welches=106;
  299.  
  300. PROCEDURE TuWas(    Dies:Typ;
  301.                 VAR Jenes:Art):BOOLEAN;
  302.   CONST
  303.     X=1;
  304.     Y=10;
  305.   VAR
  306.     Zähler:INTEGER;
  307.   BEGIN
  308.     FOR Zähler:=X TO Y DO
  309.       Action(Dies,Jenes);
  310.     END
  311.     RETURN Jenes=welches
  312.   END TuWas;
  313.  
  314.  
  315. Alte Module müssen nicht sofort neu formatiert werden, von
  316. Neuerscheinungen wird das obige Format allerdings gefordert.
  317. Die Regeln werden ständig ergänzt.
  318.